Creating and Drawing Pictures

Use the OpenCPicture function to begin defining a picture. OpenCPicture collects your subsequent QuickDraw drawing commands in a new Picture record. To complete the collection of drawing and picture comment commands that define your picture, use the ClosePicture procedure.

Operations with the following routines are not recorded in pictures: CopyMask , CopyDeepMask , SeedFill , SeedCFill , CalcMask , CalcCMask , and PlotCIcon .

You pass information to OpenCPicture in the form of an OpenCPicParams record. This record provides a simple mechanism for specifying resolutions when creating images. For example, applications that create pictures from scanned images can specify resolutions higher than 72 dpi for these pictures in OpenCPicParams records.

Listing 7-1 shows an application-defined routine, MyCreateAndDrawPict , that begins creating a picture by assigning values to the fields of an OpenCPicParams record. In this example, the normal screen resolution of 72 dpi is specified as the picture's resolution. You also specify a rectangle for best displaying the picture at this resolution.

Listing 1 Creating and drawing a picture



 
FUNCTION MyCreateAndDrawPict(pFrame: Rect): PicHandle;

CONST

    cHRes = $00480000;          {for 72 dpi}

    cVRes = $00480000;          {for 72 dpi}

VAR

    myOpenCPicParams:       OpenCPicParams;

    myPic:                  PicHandle;

    trianglePoly:           PolyHandle;

BEGIN

    WITH myOpenCPicParams DO BEGIN

        srcRect := pFrame;          {best rectangle for displaying this picture}

        hRes := cHRes;              {horizontal resolution}

        vRes := cVRes;              {vertical resolution}

        version := - 2;             {always set this field to -2}

        reserved1 := 0;             {this field is unused}

        reserved2 := 0;             {this field is unused}

    END;

    myPic := OpenCPicture(myOpenCPicParams);                {start creating the picture}

    ClipRect(pFrame);                                   {always set a valid clip region}

    FillRect(pFrame,dkGray);            {create a dark gray rectangle for background}

    FillOval(pFrame,ltGray);            {overlay the rectangle with a light gray oval}

    trianglePoly := OpenPoly;           {start creating a triangle}

    WITH pFrame DO BEGIN

        MoveTo(left,bottom);

        LineTo((right - left) DIV 2,top);

        LineTo(right,bottom);

        LineTo(left,bottom);

    END;

    ClosePoly;                          {finish the triangle}

    PaintPoly(trianglePoly);            {paint the triangle}

    KillPoly(trianglePoly);             {dispose of the memory for the triangle}

    ClosePicture;                       {finish the picture}

    DrawPicture(myPic,pFrame);                  {draw the picture}

    IF QDError <> noErr THEN

        ; {likely error is that there is insufficient memory}

    MyCreateAndDrawPict := myPic;

END;

After assigning values to the fields of an OpenCPicParams record, the MyCreateAndDrawPict routine passes this record to the OpenCPicture function.

Always use the ClipRect procedure to specify a clipping region appropriate for your picture before you call OpenCPicture . If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture scales the clipping region--in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when you draw it. Setting a clipping region equal to the port rectangle of the current graphics port, as shown in Listing 7-1 , always sets a valid clipping region.

The MyCreateAndDrawPict routine uses QuickDraw commands to draw a filled rectangle, a filled oval, and a black triangle. These commands are stored in the Picture record.

If there is insufficient memory to draw a picture in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code noMemForPictPlaybackErr .

The MyCreateAndDrawPict routine concludes the picture definition by using the ClosePicture procedure. By passing to the DrawPicture procedure the handle to the newly defined picture, MyCreateAndDrawPict replays in the current graphics port the drawing commands stored in the Picture record. Figure 7-3 shows the resulting figure.

Figure 3 A simple picture

After using DrawPicture to draw a picture, your application can use the Window Manager procedure SetWindowPic to save a handle to the picture in the window record. When the window's content region must be updated, the Window Manager draws this picture, or only a part of it as necessary, instead of generating an update event. Another Window Manager routine, the GetWindowPic function, allows your application to retrieve the picture handle that you store using SetWindowPic . When you use the Window Manager procedure DisposeWindow to close a window, DisposeWindow automatically calls the KillPicture procedure to release the memory allocated to a picture referenced in the window record. These routines and the window record are described in the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials .

Previous | Chapter Top | Chapter Contents | Next